---
title: usePipecatConnectionState
description: Hook that provides a simplified connection state for Pipecat transport.
---

## Overview

`usePipecatConnectionState` derives a simplified connection state from Pipecat transport, mapping to `disconnected`, `connecting`, and `connected`. 

This hook is designed to simplify UI state management for controls that only need to know the connectivity status.

## Usage

**What is the difference from `usePipecatClientTransportState`**

`usePipecatClientTransportState` returns the full transport state, useful when you need to know the exact state of the transport:

```tsx
import { usePipecatClientTransportState } from "@pipecat-ai/voice-ui-kit";

const transportState = usePipecatClientTransportState();

// "disconnected", "initializing", "initialized", "authenticating", "authenticated", "connecting", "connected", "ready", "disconnecting"
```

See: [usePipecatClientTransportState](https://docs.pipecat.ai/client/js/transports/transport#transport-states).

`usePipecatConnectionState` returns a simplified connection state that is useful for UI controls:

### Basic

```tsx
import { usePipecatConnectionState } from "@pipecat-ai/voice-ui-kit";

export function ConnectButton() {
  const { isConnected, isConnecting } = usePipecatConnectionState();
  
  return (
    <button
      disabled={!isConnected}
      onClick={handleConnect}
    >
      {isConnected ? "Connected" :
       isConnecting ? "Connecting..." : "Connect"}
    </button>
  );
}
```

### With loading states

```tsx
import { usePipecatConnectionState } from "@pipecat-ai/voice-ui-kit";

export function ConnectionStatus() {
  const { state, isConnected, isConnecting, isDisconnected } = usePipecatConnectionState();
  
  return (
    <div>
      <div className={`status-indicator ${state}`}>
        {isConnected && "✓ Connected"}
        {isConnecting && "⟳ Connecting..."}
        {isDisconnected && "✗ Disconnected"}
      </div>
    </div>
  );
}
```

### Full example with conditional rendering

```tsx
import React from "react";
import { usePipecatConnectionState } from "@pipecat-ai/voice-ui-kit";

export function ConnectionControls() {
  const { isConnected, isConnecting, isDisconnected } = usePipecatConnectionState();
  
  const getButtonText = () => {
    if (isConnected) return "Disconnect";
    if (isConnecting) return "Connecting...";
    return "Connect";
  };
  
  const getStatusColor = () => {
    if (isConnected) return "green";
    if (isConnecting) return "yellow";
    return "red";
  };
  
  return (
    <div className="connection-controls">
      <div className={`status-led ${getStatusColor()}`} />
      <button
        disabled={isConnecting}
        onClick={isConnected ? handleDisconnect : handleConnect}
      >
        {getButtonText()}
      </button>
      
      {isConnecting && (
        <div className="loading-spinner" />
      )}
    </div>
  );
}
```

---

## API

### Return

<TypeTable
  className="text-sm"
  type={{
    state: {
      description: "The simplified connection state derived from Pipecat transport states",
      type: "PipecatConnectionState",
      required: true,
    },
    isConnected: {
      description: "True when the connection is established and ready",
      type: "boolean",
      required: true,
    },
    isConnecting: {
      description: "True when attempting to establish a connection",
      type: "boolean",
      required: true,
    },
    isDisconnected: {
      description: "True when disconnected or in an error state",
      type: "boolean",
      required: true,
    },
  }}
/>

### Types

<TypeTable
  className="text-sm"
  type={{
    PipecatConnectionState: {
      description: "Simplified connection states for UI controls",
      type: '"disconnected" | "connecting" | "connected"',
      required: true,
    },
    PipecatConnectionStateResult: {
      description: "Return type for the usePipecatConnectionState hook",
      type: "object",
      required: true,
    },
  }}
/>
